Skip to content

Add image template functions docs for EC v3#3940

Open
sgalsaleh wants to merge 10 commits intomainfrom
docs/ec-image-template-functions
Open

Add image template functions docs for EC v3#3940
sgalsaleh wants to merge 10 commits intomainfrom
docs/ec-image-template-functions

Conversation

@sgalsaleh
Copy link
Copy Markdown
Member

@sgalsaleh sgalsaleh commented Apr 10, 2026

Document ReplicatedImageName, ReplicatedImageRegistry, ReplicatedImageRepository, and HelmValue template functions with recommended setup patterns for online and air gap installations.

Document ReplicatedImageName, ReplicatedImageRegistry,
ReplicatedImageRepository, ImagePullSecretName, and HelmValue
template functions with recommended setup patterns for online
and air gap installations.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sgalsaleh sgalsaleh requested a review from a team as a code owner April 10, 2026 16:24
@netlify
Copy link
Copy Markdown

netlify bot commented Apr 10, 2026

Deploy Preview for replicated-docs ready!

Name Link
🔨 Latest commit f917f66
🔍 Latest deploy log https://app.netlify.com/projects/replicated-docs/deploys/69dc1ca987f7a00008ecd301
😎 Deploy Preview https://deploy-preview-3940--replicated-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@replicated-ci replicated-ci added type::docs Improvements or additions to documentation type::feature labels Apr 10, 2026
@netlify
Copy link
Copy Markdown

netlify bot commented Apr 10, 2026

Deploy Preview for replicated-docs-upgrade ready!

Name Link
🔨 Latest commit f917f66
🔍 Latest deploy log https://app.netlify.com/projects/replicated-docs-upgrade/deploys/69dc1ca92c88d10008f51bda
😎 Deploy Preview https://deploy-preview-3940--replicated-docs-upgrade.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

### ReplicatedImageRepository

```go
func ReplicatedImageRepository(repository string, noProxy ...bool) string
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

its awkward reading go code here. its not obvious that noProxy is optional or what the intention of the ... is

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, updating. ty

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this matches our docs elsewhere for template functions...

@@ -1,11 +1,11 @@
For each image reference in your Helm chart values file, set the image repository URL to the location of the image in the proxy registry.
For each Helm chart used by your application, in the Helm chart's `values.yaml` file, update all references to private or third-party images to use the Replicated proxy registry domain.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[Replicated.SentenceLength] Try to keep your sentence length to 26 words or fewer.

These steps assume that you package your application with Helm and that you install with the [HelmChart v2](/reference/custom-resource-helmchart-v2) custom resource.

If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure Other Application Types](#other) below.
If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure other application types](#other) below.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[Replicated.SentenceLength] Try to keep your sentence length to 26 words or fewer.

These steps assume that you package your application with Helm and that you install with the [HelmChart v2](/reference/custom-resource-helmchart-v2) custom resource.

If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure Other Application Types](#other) below.
If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure other application types](#other) below.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Replicated.PositionalLanguage] Avoid spacial and directional language like 'below'. Instead, use 'on this page', 'the following', or link to the section.

If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure Other Application Types](#other) below.
If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure other application types](#other) below.

### Embedded Cluster v3 (Beta) {#configure-v3}
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Replicated.Headings] 'Embedded Cluster v3 (Beta) ***************' should use sentence case.

@@ -0,0 +1,212 @@
# Image Template Functions for Embedded Cluster (Beta)
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Replicated.Headings] 'Image Template Functions for Embedded Cluster (Beta)' should use sentence case.


- When referencing Docker Hub images through the Replicated proxy registry, use the full path including `docker.io` and the namespace. For official images, this means including `library`. For example, to proxy the `nginx` image, use `proxy.replicated.com/proxy/my-app/docker.io/library/nginx` (not `proxy.replicated.com/proxy/my-app/nginx`). For other Docker Hub images, include the organization (for example, `proxy.replicated.com/proxy/my-app/docker.io/bitnami/postgresql`).

## Function Reference
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Replicated.Headings] 'Function Reference' should use sentence case.


Returns a full image reference (registry + repository + tag). Use this when a chart expects the entire image reference in a single field. The optional `noProxy` parameter, when set to `true`, leaves the image unchanged in online mode.

| Mode | noProxy | Result |
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?


Returns the registry host. Use this when a chart splits the image reference into separate `registry` and `repository` fields. The optional `noProxy` parameter, when set to `true`, returns the input registry unchanged in online mode.

| Mode | noProxy | Result |
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?


Returns the repository path. Use this together with `ReplicatedImageRegistry`. The optional `noProxy` parameter, when set to `true`, returns the input repository unchanged in online mode.

| Mode | noProxy | Result |
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?


Returns the value from the chart's `values.yaml` at the given dotted path. Use this to read the chart's default image values and pass them to image template functions.

## KOTS-Compatible Aliases
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Replicated.Headings] 'KOTS-Compatible Aliases' should use sentence case.

@@ -0,0 +1,199 @@
# Template Functions for Embedded Cluster (Beta)
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Replicated.Headings] 'Template Functions for Embedded Cluster (Beta)' should use sentence case.

@@ -0,0 +1,199 @@
# Template Functions for Embedded Cluster (Beta)

This topic lists the Replicated template functions for Embedded Cluster. For more imformation about how to use Replicated template functions, including a list of all available template functions, see [About Template Functions](/reference/template-functions-about).
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'imformation'?

initImage: '{{repl ReplicatedImageName (HelmValue ".initImage") true }}'
```

#### Return a value from a subchart
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'subchart'?


### Parameters

#### image
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Replicated.Headings] 'image' should use sentence case.


Use the [HelmValue](#helmvalue-func) function to return the value from the chart's `values.yaml` at the given dotted path.

#### noProxy
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?


### Parameters

#### image
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Replicated.Headings] 'image' should use sentence case.


Use the [HelmValue](#helmvalue-func) function to return the value from the chart's `values.yaml` at the given dotted path.

#### noProxy
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Replicated.Headings] 'noProxy' should use sentence case.


Use the [HelmValue](#helmvalue-func) function to return the value from the chart's `values.yaml` at the given dotted path.

#### noProxy
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?


#### noProxy

The following table describes the value returned by ReplicatedImageName in online or air gap installations, when the `noProxy` field is omitted or set to `true`:
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is omitted').


The following table describes the value returned by ReplicatedImageName in online or air gap installations, when the `noProxy` field is omitted or set to `true`:

| Install type | noProxy | Result |
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?


### Parameters

#### image
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Replicated.Headings] 'image' should use sentence case.

The image reference to rewrite.
Use the [HelmValue](#helmvalue-func) function to return the value from the chart's `values.yaml` at the given dotted path.

#### noProxy
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?

The image reference to rewrite.
Use the [HelmValue](#helmvalue-func) function to return the value from the chart's `values.yaml` at the given dotted path.

#### noProxy
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Replicated.Headings] 'noProxy' should use sentence case.


#### noProxy

The following table describes the value returned by ReplicatedImageName in online or air gap installations when the `noProxy` field is omitted or set to `true`:
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is omitted').


The following table describes the value returned by ReplicatedImageName in online or air gap installations when the `noProxy` field is omitted or set to `true`:

| Install type | noProxy | Result |
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?


#### noProxy

The following table describes the value returned by ReplicatedImageName in online or air gap installations, when the `noProxy` field is omitted or set to `true`:
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is omitted').

To create an application release that supports installation with Embedded Cluster v3:

To add the Embedded Cluster Config:
1. If you use the Replicated proxy registry, update all references to private or third-party images to use the Replicated proxy registry domain. See the _Embedded Cluster v3_ steps in [Configure your application to use the proxy registry](/vendor/private-images-kots#configure-v3).
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This links to the existing docs on how to rewrite image refs in your values file to use the proxy domain. I've updated those docs to add a new subsection for EC v3.

* `EXTERNAL_REGISTRY_IMAGE_URL` is the path to the private image on your external registry.
- `DOMAIN` is either `proxy.replicated.com` or your custom domain
- `APP_SLUG` is the unique slug of your application
- `UPSTREAM_REGISTRY/IMAGE_PATH` is the full upstream image path. For example, `ghcr.io/my-org/my-image` or `docker.io/bitnami/postgresql`.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated this guidance to use "upstream" terminology instead of "external" based on Salah's language in embedded-image-template-functions.mdx

* LocalImageName

These template functions are typically used to conditionally rewrite image references in air gap installations to reference the local image registry. For Embedded Cluster v3 installations, use the ReplicatedImageName, ReplicatedImageName, and ReplicatedImageName template functions instead. For more information, see [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ Added this limitation to call out that the image temp funcs are not supported in ec v3 installations


:::note
The LocalRegistryAddress template function is not supported for installations with Embedded Cluster v3. See [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions).
:::
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added these notes to each of the unsupported image templates functions

If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure Other Application Types](#other) below.
If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure other application types](#other) below.

### Embedded Cluster v3 (Beta) {#configure-v3}
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added these new steps for ECv3. The main difference is that you don't need to inject the image pull secret anymore since EC v3 automatically configures the cluster to authenticate to the proxy registry for all pods

import RewriteHelmValues from "../docs/partials/proxy-service/_step-rewrite-helm-values.mdx"
import DependencyYaml from "../docs//partials/replicated-sdk/_dependency-yaml.mdx"

# Configure Embedded Cluster (Beta)
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

my goal with this page is that ECv3 vendors won't need to reference the existing https://docs.replicated.com/vendor/helm-native-v2-using in the KOTS docs in order to configure HelmChart v2 for ECv3 installations

values:
initImage: '{{repl ReplicatedImageName (HelmValue ".initImage") true }}'
```
ReplicatedImageName sets `noProxy` to `true` because the image reference value in `values.yaml` already contains the proxy path prefix (`proxy.replicated.com/proxy/my-app/...`)
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added a question here about when to use noProxy https://github.com/replicatedhq/replicated-docs/pull/3940/changes#r3070284069

Image template functions automatically rewrite image references based on the installation mode:

- **Online**: Images are served through the Replicated proxy registry (`proxy.replicated.com` or your custom domain). Images that do not need to go through the proxy can be left unchanged using the `noProxy` parameter.
- **Air gap**: All images are rewritten to the local registry regardless of the `noProxy` parameter.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All images are rewritten to the local registry

Does this refer to the Embedded Cluster built-in local registry? Or are there cases where the user is able to bring their own local registry?

|------|---------|--------|
| Online | Omitted | Returns the proxy registry URL for the image in the format: `proxy.replicated.com/proxy/<app-slug>/<image>`, where `app-slug` is the unique application slug |
| Online | `true` | Returns the image reference with no changes |
| Air gap | `true` or omitted | Returns the location of the image at the local image registry in the format: `<local-registry>/<app-slug>/<name>:<tag>` |
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does local-registry here always mean EC's built-in image registry? Or is the user able to bring their own local registry?

https://github.com/replicatedhq/replicated-docs/pull/3940/changes#r3070292020

//REFERENCE DOCS
{ type: "html", value: "<h5>Reference</h5>", defaultStyle: true },
"embedded-config",
"template-functions",
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

moved these to a Reference section in the sidebar

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type::docs Improvements or additions to documentation type::feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants